{"uid":"cap_56G1e_SEeB5m1D5TNT1CJ","slug":"scheduler-withzero-xyz-queue-ad-hoc-test-run-for-scheduled-task-09738663","name":"Queue Ad-Hoc Test Run for Scheduled Task","description":"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","url":"https://scheduler.withzero.xyz/api/v1/tasks/{id}/runs","method":"POST","headers":{},"bodySchema":{"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},"responseSchema":{"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},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":3,"rating":{"score":"0.69","successRate":"0.83","reviews":3,"stars":"3.8","state":"rated"},"availabilityStatus":"healthy","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"metered","summary":"metered — billed by usage","primary":{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_ufd1NFhtr0tpXd8UEDmZf","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x20C000000000000000000000b9537d11c60E8b50","unit":"request","depositMicros":null,"planRef":"scheduler.tasks.runs.create:1"}],"brandName":"scheduler.withzero.xyz","brandSlug":"scheduler-withzero-xyz-mpp","brandBaseUrl":"https://scheduler.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Triggers an immediate one-off test invocation of a scheduled task without advancing its next scheduled run time.","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Test a new cron task before deploying","prompt":"I just set up a new scheduled task to send daily digest emails. Can you run it right now so I can verify it works and see the actual output before it runs automatically tomorrow?"},{"title":"Debug a failing scheduled job on demand","prompt":"My backup task has been failing silently for a few hours. Trigger an immediate run of it so I can see what's going wrong and validate my fix without waiting until the next scheduled cycle."},{"title":"Manually execute recurring task outside schedule","prompt":"We need to process our data reconciliation task outside its normal weekly schedule because we just loaded new data. Fire it off immediately without changing when it's supposed to run next week."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":"# Run Task Now — synchronous ad-hoc run\n\n## Workflow\n- Needs a task id from: POST /api/v1/tasks (create)\n- Async alternative: POST /api/v1/tasks/{id}/trigger (returns immediately)\n- Full stdout/stderr after: GET /api/v1/runs/{id}\n\n## Contract\n- Blocks until the run finalizes, then returns it. Billed like a normal cron run (draws the deposit).\n- Does NOT advance next_run_at — safe for smoke-testing a cron before trusting its schedule.\n- Fails if balance < one run's ceiling — top up via POST /api/v1/tasks/{id}/fund.","reviewSummary":"This synchronous task-execution capability blocks until a run finalizes and returns the run ID, making it useful for on-demand testing and smoke-testing schedulers after deploys. Performs well in successful cases, completing in roughly 10 seconds with accurate results, but a documented timeout bug can cause the client to report failure even when the task was successfully created server-side, risking duplicate on-demand tasks. Reviews are mixed, with two strong successes and one reliability-critical failure.","reviewSummaryHighlights":["Blocks synchronously and returns the run ID on success","Effective for smoke-testing schedulers after deployment changes"],"reviewSummaryConcerns":["Client timeout can misreport failure after a successful server-side task creation, leaving orphaned tasks","POST body requires explicit empty JSON object ({}) despite schema implying no body needed"],"reviewSummaryGeneratedAt":"2026-08-19T00:15:10.816Z","activationCount":130,"lastUsedAt":"2026-09-02T00:53:09.724Z","lastSuccessfullyRanAt":"2026-09-02T00:53:09.724Z","lastHealthCheckAt":"2026-09-11T00:38:51.730Z","isFirstParty":true}