# Fetch Task by ID (Owner-Gated)

> Fetch Task by ID (Owner-Gated) is a free API for AI agents from scheduler.withzero.xyz, callable via MPP, free · handshake required, status healthy (last checked 2026-09-09, last successful call 2026-09-15).

Retrieves the full details of a scheduled cron task by its UUID, gated to the task owner via proof; environment variables are never returned.

## Facts

- Endpoint: GET https://scheduler.withzero.xyz/api/v1/tasks/{id}
- Price: free · handshake required
- Payment: MPP
- Status: healthy
- Last checked: 2026-09-09
- Last successful call: 2026-09-15
- Success rate: 100% of calls made through Zero
- Rating: 5.0 / 5 from 2 reviews
- Activations on Zero: 1567
- Provider: scheduler.withzero.xyz
- Website: https://scheduler.withzero.xyz
- Canonical page: https://www.zero.xyz/c/scheduler-withzero-xyz-fetch-task-by-id-owner-gated-8b2aaf13
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_DHRxsX4SuGoAZjjq76loV

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-fetch-task-by-id-owner-gated-8b2aaf13
```

Example prompt: Can you pull up the full details for my cron task with ID 3f2a1b4c-1234-4abc-89de-000000000001 on the Zero scheduler — I want to see its status, next run time, and how much balance is left in the payment channel?

## When to prefer this

Use this endpoint when you need to read the current state, configuration, or cost/billing metrics of a specific scheduled task and you hold proof of ownership. Prefer this over listing endpoints when you already know the task UUID.

## Known failure modes

- 401/403 if the caller cannot prove ownership of the task
- 404 if the task UUID does not exist
- 400 if the UUID format is invalid
- Service unavailable if the scheduler backend is down

## How this service works

Fetch a task. Owner-gated by proof. `env` is never returned. 📖 Full guide: https://scheduler.withzero.xyz/llms.txt

## Output

Returns a JSON object containing the full task record: UUID, owner, status, cron expression, timezone, runtime, entrypoint, source, dependencies, tool list, LLM config, notification email, max runtime seconds, max sibling calls, payment channel ID and transaction hashes, cost metrics (max, cumulative, latest voucher, available balance, estimated ceiling, lifetime cost), lifetime run count, average cost per run, next and last run timestamps, end date, pause reason, recovery hint with top-up instructions if applicable, and created/updated timestamps. The env blob is never included.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "id"
 ],
 "properties": {
  "id": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "id",
  "owner",
  "status",
  "billing_rail",
  "cron",
  "timezone",
  "runtime",
  "entrypoint",
  "source",
  "dependencies",
  "tool_list",
  "llm",
  "notify_email",
  "max_runtime_sec",
  "max_sibling_calls",
  "channel_id",
  "channel_open_tx",
  "channel_close_tx",
  "max_amount_micros",
  "cumulative_cost_micros",
  "latest_voucher_micros",
  "balance_available_micros",
  "estimated_ceiling_micros",
  "lifetime_cost_micros",
  "lifetime_runs",
  "avg_cost_per_run_micros",
  "next_run_at",
  "last_run_at",
  "end_at",
  "last_paused_reason",
  "last_paused_at",
  "recovery_hint",
  "created_at",
  "updated_at"
 ],
 "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)$"
  },
  "llm": {
   "anyOf": [
    {},
    {
     "type": "null"
    }
   ]
  },
  "cron": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "owner": {
   "type": "string"
  },
  "end_at": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "source": {
   "type": "string"
  },
  "status": {
   "type": "string"
  },
  "runtime": {
   "type": "string"
  },
  "timezone": {
   "type": "string"
  },
  "tool_list": {
   "anyOf": [
    {
     "type": "array",
     "items": {
      "type": "string"
     }
    },
    {
     "type": "null"
    }
   ]
  },
  "channel_id": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "description": "Direct rail payment channel/challenge id. Null on the ZeroClick rail."
  },
  "created_at": {
   "type": "string"
  },
  "entrypoint": {
   "type": "string"
  },
  "updated_at": {
   "type": "string"
  },
  "last_run_at": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "next_run_at": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "billing_rail": {
   "enum": [
    "direct",
    "zeroclick",
    "account"
   ],
   "type": "string"
  },
  "dependencies": {
   "anyOf": [
    {},
    {
     "type": "null"
    }
   ]
  },
  "notify_email": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ]
  },
  "lifetime_runs": {
   "ty
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/scheduler-withzero-xyz-fetch-task-by-id-owner-gated-8b2aaf13/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)