---
title: "Create a scheduled test job"
method: POST
path: "/ai/tests/schedules/v1/cron-jobs"
tags: ["AI Tests"]
---

# Create a scheduled test job

`POST /ai/tests/schedules/v1/cron-jobs`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/ai/tests/schedules/v1/cron-jobs`
- Auth: HTTP bearer

Creates a scheduled test job that runs the selected scenarios on a cron expression.

## Request body

- CreateScheduledTestJobRequest
  - `crontab_expression` string, required: Cron expression controlling when the job runs.
  - `name` string
  - `scenarios` integer[]
  - `tags` string[]
  - `agent` integer
  - `timezone` string
  - `personalities` integer[]
  - `execution_mode` string: Execution mode for the test runs, such as voice, text, or sip.
  - `frequency` integer
  - `run_as_text` boolean
  - `notify_on` 'never' | 'success' | 'failure' | 'both'
  - `is_active` boolean

## Response `200`

Scheduled test job created.

- ScheduledTestJob
  - `id` integer, required
  - `name` string, required
  - `agent` integer, required: ID of the test agent the job belongs to.
  - `crontab_expression` string, required: Cron expression controlling when the job runs, in the job's timezone.
  - `timezone` string
  - `scenario_ids` integer[]: Scenario IDs the job executes.
  - `scenarios_data` object[]
    - `id` integer
    - `agent` integer
    - `name` string
    - `personality` integer, nullable
    - `personality_name` string
  - `personality` integer, nullable
  - `personalities` integer[]
  - `tags` string[]
  - `frequency` integer
  - `run_as_text` boolean: Whether the job runs scenarios as text chat rather than voice calls.
  - `execution_mode` string: Execution mode for the test runs, such as voice, text, or sip.
  - `notify_on` 'never' | 'success' | 'failure' | 'both': When the job sends a notification.
  - `is_active` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad Request. The AI Tests service rejected the request.
- `401`: Unauthorized. Missing or invalid API key.
- `404`: Not Found. The requested resource does not exist or is not enabled for your account.
- `422`: Unprocessable Entity. A validation error occurred.
- `429`: Too Many Requests. The AI Tests service rate-limited the request.
- `503`: Service Unavailable. The AI Tests service is unavailable.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-22** `09b2e45a88da`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/tests/schedules/v1/cron-jobs/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)