# WithZero Scheduler - Create Task

> WithZero Scheduler - Create Task is a paid API for AI agents from agents.withzero.xyz, paid per call via MPP, $1/call, status healthy (last checked 2026-09-15, last successful call 2026-09-04).

Creates a new recurring (cron-scheduled) or on-demand AI agent task with escrow-based billing, optional LLM access, tool lists, dependencies, and environment variables.

## Facts

- Endpoint: POST https://agents.withzero.xyz/api/v1/scheduler/tasks
- Price: $1/call
- Payment: MPP
- Status: healthy
- Last checked: 2026-09-15
- Last successful call: 2026-09-04
- Success rate: 100% of calls made through Zero
- Activations on Zero: 2
- Provider: agents.withzero.xyz
- Website: https://agents.withzero.xyz
- Canonical page: https://www.zero.xyz/c/agents-withzero-xyz-withzero-scheduler-create-task-a028a012
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_egrcNnMIFeEO6NNHl4BbT

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 agents-withzero-xyz-withzero-scheduler-create-task-a028a012 -d '<json body>'
```

Example prompt: Schedule a recurring daily task at 8am UTC using the 'standard' LLM profile that scrapes competitor pricing data and emails me a summary — set the max runtime to 120 seconds, a lifetime cap of $5 USDC, and inject my API key as COMPETITOR_API_KEY in the environment.

## When to prefer this

Use this endpoint when you need to create a new autonomous agent task — either scheduled on a cron or triggered on-demand — with a defined spending cap and optional LLM access. Prefer the direct rail when you want refundable USDC escrow linked to a payment channel; prefer ZeroClick when operating through a marketplace where access is marketplace-authoritative. Use this over generic cloud scheduler services when your task needs built-in LLM broker access, pay-per-use billing, and no vendor API key management.

## Known failure modes

- 400 PRICE_RESOLVER_FAILED — X-Pay-Amount-Micros header is missing, non-integer, or does not exactly match max_amount_usdc_micros in the request body
- 400 validation error — required fields (runtime, source, entrypoint, max_runtime_sec, max_sibling_calls, max_amount_usdc_micros) are missing or malformed
- 402 Payment Required — payment challenge not satisfied by the client before task is created
- 409 conflict — same Idempotency-Key reused with a different body (different semantics from safe retry)
- 429 rate limit — too many task creation requests in a short window
- 500 internal error — sandbox provisioning or payment channel open failure

## How this service works

Create a recurring or on-demand task. Direct endpoint: max_amount_usdc_micros is refundable escrow and X-Pay-Amount-Micros must match it. ZeroClick endpoint: it is a seller-local lifetime execution cap; marketplace access/usage is authoritative and no seller escrow is created. Optional: schedule, max_sibling_calls, llm, tool_list, dependencies, env, notify_email, end_at. See GET /api/v1 and /llms.txt for rail-specific setup.

## Output

Returns a JSON object containing the new task's UUID, initial status, next scheduled run timestamp, billing rail (direct or zeroclick), payment channel ID and opening transaction hash, maximum escrow amount, current available balance, estimated execution ceiling (all in USDC micros), the cron expression, and timezone.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "runtime",
  "source",
  "entrypoint",
  "max_runtime_sec",
  "max_sibling_calls",
  "max_amount_usdc_micros"
 ],
 "properties": {
  "env": {
   "type": "object",
   "description": "BYO env vars injected into the sandbox. Never returned in any GET response.",
   "propertyNames": {
    "type": "string",
    "pattern": "^[A-Z_][A-Z0-9_]*$"
   },
   "additionalProperties": {
    "type": "string",
    "maxLength": 4096
   }
  },
  "llm": {
   "type": "object",
   "required": [
    "profile"
   ],
   "properties": {
    "model": {
     "type": "string",
     "pattern": "^[a-z][a-z0-9-]*(\\/[A-Za-z0-9._:-]+)?$",
     "description": "Optional preferred model selector used when sandbox code omits a model."
    },
    "models": {
     "type": "array",
     "items": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*(\\/[A-Za-z0-9._:-]+)?$"
     },
     "maxItems": 16,
     "minItems": 1,
     "description": "Optional allowlist of internal LLM aliases or provider/model ids this task may use. Defaults from the profile."
    },
    "profile": {
     "enum": [
      "quick",
      "standard",
      "bulk",
      "research",
      "long"
     ],
     "type": "string",
     "default": "standard",
     "description": "LLM workload envelope. Use 'quick', 'standard', 'bulk', 'research', or 'long'."
    },
    "max_calls_per_run": {
     "type": "integer",
     "maximum": 100,
     "description": "Optional lower hard cap on LLM broker calls per run.",
     "exclusiveMinimum": 0
    },
    "max_input_bytes_per_call": {
     "type": "integer",
     "maximum": 1048576,
     "description": "Optional lower hard cap on UTF-8 prompt+system bytes per LLM call.",
     "exclusiveMinimum": 0
    },
    "max_output_tokens_per_call": {
     "type": "integer",
     "maximum": 128000,
     "description": "Optional lower hard cap on generated tokens requested from the broker.",
     "exclusiveMinimum": 0
    },
    "max_cost_usdc_micros_per_run": {
     "type": "string",
     "pattern": "^[1-9]\\d*$",
     "description": "Optional lower per-run LLM spend ceiling in USDC micros (string or number). Added to the task claim ceiling."
    }
   },
   "description": "Enables the built-in LLM for your source (call generate_text(...) — pre-imported, auto-authenticated). Omit to disable LLM calls. Pick a profile (quick|standard|bulk|research|long); GET /api/v1/rates → llm_profiles lists each pro
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "id",
  "status",
  "next_run_at",
  "billing_rail",
  "channel_id",
  "channel_open_tx",
  "max_amount_micros",
  "balance_available_micros",
  "estimated_ceiling_micros",
  "cron",
  "timezone"
 ],
 "properties": {
  "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)$"
  },
  "cron": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "status": {
   "type": "string"
  },
  "timezone": {
   "type": "string"
  },
  "channel_id": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "next_run_at": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "billing_rail": {
   "enum": [
    "direct",
    "zeroclick"
   ],
   "type": "string"
  },
  "channel_open_tx": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "max_amount_micros": {
   "type": "string"
  },
  "balance_available_micros": {
   "type": "string"
  },
  "estimated_ceiling_micros": {
   "type": "string"
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agents-withzero-xyz-withzero-scheduler-create-task-a028a012/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.withzero.xyz](https://www.zero.xyz/host/agents.withzero.xyz/llms.txt)