# Run a cron schedule now

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

Contract status: **implemented**. This page describes a mounted route; the authenticated capability response remains the authority for current account access.

## Request

`POST /api/agent/v1/automations/cron/{cronJobRef}/runs`

Operation ID: `runAgentCronJob`

Send a short-lived access token obtained through [auth.md](https://neotask.ai/auth.md) for `https://neotask.ai/api/agent` in the `Authorization: Bearer` header. The token must include `neotask:cron:run`.

Send an `Idempotency-Key` header with 8-200 characters. Reuse it only for an identical retry. For 24 hours, an identical retry returns the outcome recorded for the first request, with the same status and body, instead of running the operation again; a recorded failure is returned as that same failure. A readiness refusal returned before the operation started (for example `setup_required` with `runner_not_enrolled`, or `temporarily_disabled` with `run_execution_disabled`, `runner_offline` or `cloud_gateway_not_connected`) is not recorded, so the identical retry runs once the runner or gateway is ready.

The JSON request body uses `AgentCronRunRequest` in OpenAPI.

## Response

The accepted run and updated schedule projection. The JSON schema is `AgentCronRunResponse` in [OpenAPI](https://neotask.ai/openapi.yaml).

- With no enrolled runner, the route returns setup_required with reason runner_not_enrolled. An enrolled but unreachable runner returns temporarily_disabled with reason runner_offline.
- The scheduled trigger is metadata only; no timer or watchdog is an LLM, tool, or approval timeout and no replacement run is created.

## Errors

| HTTP | Codes | Meaning | Next action |
|---:|---|---|---|
| 400 | `invalid_request`, `invalid_idempotency_key` | The request body or Idempotency-Key is malformed. | Correct the documented input. Reuse an idempotency key only for the identical mutation. |
| 404 | `not_found` | The tenant-scoped resource does not exist or is not visible to this principal. | Do not try another tenant identifier. Re-read the tenant-scoped resource list. |
| 409 | `setup_required`, `conflict` | No eligible runner is enrolled for this agent principal. A conflict with reason run_authority_stale means the accepted run no longer matches its initiating authority. | Follow the runner setup state returned by capabilities. Do not invent a runner id or credential. For run_authority_stale, inspect the current run and account access before retrying; do not create duplicate work. |
| 503 | `temporarily_disabled` | Run execution is disabled, the runner store is unavailable, or an enrolled runner is offline. | Read capabilities and retry only after the returned runner state changes. |
| 409 | `idempotency_conflict`, `idempotency_in_progress`, `conflict` | The idempotency key belongs to another request or its first request is still running. A conflict with reason run_authority_stale means the accepted run no longer matches its initiating authority. | Do not change the request under the same key. Retry later or use a new key for new work. For run_authority_stale, inspect the current run and account access before retrying; do not create duplicate work. |
| 403 | `scope_denied`, `tenant_inactive`, `model_not_allowed`, `claim_required` | The credential, claim state, account, or selected model cannot start this execution. | Complete the documented claim, use an allowed model, request the documented scope, or ask the user to restore account access. |
| 401 | `invalid_credential`, `principal_not_linked`, `registration_revoked`, `identity_conflict` | The bearer token or linked agent principal is invalid or inactive. | Register, refresh, or claim through the documented Auth.md flow, then retry with a new token. |
| 503 | `temporarily_disabled` | Agent authentication is unavailable or feature-gated. | Do not bypass authentication. Retry only after the returned guidance or launch state changes. |
| 402 | `plan_required` | The current plan excludes this operation, or paid execution lacks an active subscription. Billing denial returns plan_required with reason billing_required. | Read capabilities and use the documented account or checkout handoff. Retry after the account has execution access. |
| 429 | `quota_exhausted` | The account message quota is exhausted, or shared HTTP admission rejected the request before the route. HTTP admission returns quota_exhausted with reason request_rate_limit. | For request_rate_limit, honor Retry-After when present. For account quota exhaustion, read usage and wait for quota renewal or an account change. |

## Related resources

- [Agent API index](https://neotask.ai/docs/llms.txt)
- [OpenAPI JSON](https://neotask.ai/openapi.json)
- [Arazzo quickstart](https://neotask.ai/arazzo.yaml)
- [Knowledge manifest](https://neotask.ai/agent-public-contracts/v1/knowledge-manifest.json)