# Queue Ad-Hoc Test Run for Scheduled Task

> Queue Ad-Hoc Test Run for Scheduled Task is a paid API for AI agents from scheduler.withzero.xyz, paid per call via MPP, metered — billed by usage, status healthy (last checked 2026-09-11, last successful call 2026-09-02).

Triggers an immediate one-off test invocation of a scheduled task without advancing its next scheduled run time.

## Facts

- Endpoint: POST https://scheduler.withzero.xyz/api/v1/tasks/{id}/runs
- Price: metered — billed by usage
- Payment: MPP
- Status: healthy
- Last checked: 2026-09-11
- Last successful call: 2026-09-02
- Success rate: 83% of calls made through Zero
- Rating: 3.8 / 5 from 3 reviews
- Activations on Zero: 130
- Provider: scheduler.withzero.xyz
- Website: https://scheduler.withzero.xyz
- Canonical page: https://www.zero.xyz/c/scheduler-withzero-xyz-queue-ad-hoc-test-run-for-scheduled-task-09738663
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_56G1e_SEeB5m1D5TNT1CJ

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability scheduler-withzero-xyz-queue-ad-hoc-test-run-for-scheduled-task-09738663 -d '<json body>'
```

Example prompt: Trigger an immediate test run of my scheduled task with ID a3f2c1d0-beef-4321-abcd-0011223344ff — I want to test it right now without pushing its next scheduled run time.

## When to prefer this

Use this endpoint when you need to immediately test or debug a specific scheduled task without disrupting its regular cron schedule. Ideal for verifying task logic after configuration changes, or triggering a one-off execution outside the normal cadence. Prefer this over waiting for the next scheduled run when iterating on task setup.

## Known failure modes

- Task ID not found: 404 if the specified task does not exist or is inaccessible to the caller
- Task is paused or deleted: may return 409 or 400 if the task is not in a runnable state
- Authentication failure: 401/403 if owner proof is missing or invalid
- Scheduler overload: 503 if the run queue is temporarily unavailable

## How this service works

Run a task right now, synchronously: claims, runs the sandbox inline, and blocks until the run finalizes, then returns it. Billed like a normal cron run. Use it to trigger an on-demand run or to test a cron you just set up before trusting the schedule. Does NOT advance next_run_at. 📖 Full guide: https://scheduler.withzero.xyz/llms.txt

## Output

Returns a JSON object containing the new run's UUID (run_id), the parent task UUID (task_id), the current status string, the trigger type, and the claimed_at timestamp — confirming the ad-hoc run has been queued.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "properties": {},
 "description": "Empty body. Runs the task immediately and synchronously — blocks until the run finalizes, then returns it.",
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "run_id",
  "task_id",
  "status",
  "trigger",
  "claimed_at"
 ],
 "properties": {
  "run_id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "status": {
   "type": "string"
  },
  "task_id": {
   "type": "string",
   "format": "uuid",
   "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  },
  "trigger": {
   "type": "string"
  },
  "claimed_at": {
   "type": "string"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/scheduler-withzero-xyz-queue-ad-hoc-test-run-for-scheduled-task-09738663/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from scheduler.withzero.xyz](https://www.zero.xyz/host/scheduler.withzero.xyz/llms.txt)