---
title: "Pause a scheduled agent"
method: POST
path: "/agent/schedules/{scheduleId}/pause"
tags: ["schedules"]
---

# Pause a scheduled agent

`POST /agent/schedules/{scheduleId}/pause`

Pause a scheduled agent. The agent will not run until resumed.

## Path parameters

- `scheduleId` string, required

## Response `200`

Scheduled agent paused successfully

- ScheduledAgentItem
  - `id` string, required — Unique identifier for the scheduled agent
  - `name` string, required — Human-readable name for the schedule
  - `cron_schedule` string, required — Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
  - `enabled` boolean, required — Whether the schedule is currently active
  - `prompt` string, required — The prompt/instruction for the agent to execute
  - `last_spawn_error` string, nullable — Error message from the last failed spawn attempt, if any
  - `agent_config` AmbientAgentConfig — Configuration for a cloud agent run
    - `name` string — Human-readable label for grouping, filtering, and traceability. Automatically set to the skill name when running a skill-based agent. Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check") so you can filter and track them via the name query parameter on GET /agent/runs.
    - `model_id` string — LLM model to use (uses team default if not specified)
    - `base_prompt` string — Custom base prompt for the agent
    - `environment_id` string — UID of the environment to run the agent in
    - `runner_id` string — UID of the runner providing the run's compute (platform, instance shape, and setup commands). When omitted on a request, the runner is resolved at run creation from the agent's default runner, then the environment's default runner, and the resolved UID is recorded on the run.
    - `skill_spec` string — Skill specification identifying the primary agent skill to use. Format: "{owner}/{repo}:{skill_path}" Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" Mutually exclusive with skills in create/update requests. Responses include the first skills entry here for backward compatibility. Use the list agents endpoint to discover available skills.
    - `skills` string[] — Ordered skill specifications to attach to the run. Format: "{owner}/{repo}:{skill_path}" Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" Mutually exclusive with skill_spec in create/update requests.
    - `mcp_servers` object — Map of MCP server configurations by name
    - `computer_use_enabled` boolean — Controls whether computer use is enabled for this agent. If not set, defaults to true.
    - `idle_timeout_minutes` integer — Number of minutes to keep the agent environment alive after task completion. If not set, defaults to 10 minutes. Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier).
    - `worker_host` string — Self-hosted worker ID that should execute this task. If not specified or set to "warp", the task runs on Warp-hosted workers.
    - `harness` Harness — Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. When stored as a named agent's default (create/update agent identity), this field replaces the deprecated base_harness/base_model pair: a non-oz type here requires the agent's base_model to be empty, since the two describe mutually exclusive default models.
      - `type` 'oz' | 'claude' | 'gemini' | 'codex' — The harness type identifier. - oz: Warp's built-in harness (default) - claude: Claude Code harness - gemini: Gemini CLI harness - codex: Codex CLI harness
      - `model_id` string — Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a non-oz harness; the top-level config model_id targets the built-in Oz harness instead. When omitted or empty, the harness uses its own default model.
      - `reasoning_level` string — Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a non-oz harness. Ignored by harnesses that do not support reasoning levels.
    - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
      - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
      - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".
    - `session_sharing` SessionSharingConfig — Configures sharing behavior for the run's shared session. When set, the worker emits `--share public:<level>` and the bundled Warp client applies an anyone-with-link ACL to the shared session once it has bootstrapped. The same ACL is mirrored onto the backing conversation so link viewers can read the conversation without being on the run's team. Subject to the workspace-level anyone-with-link sharing setting.
      - `public_access` 'VIEWER' | 'EDITOR' — Grants anyone-with-link access at the specified level to the run's shared session and backing conversation. - VIEWER: link viewers can read the session and conversation. - EDITOR: link viewers can also interact with the session. Anonymous (unauthenticated) reads are not supported in this release; link viewers must still be authenticated Warp users.
    - `memory_stores` MemoryStoreRef[] — Memory stores to attach to this run.
      - `uid` string, required — UID of the memory store.
      - `access` 'read_write' | 'read_only', required — Access level for the store.
      - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
    - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
      - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
        - `disabled` boolean — If true, opt out of Bedrock at this layer.
        - `role_arn` string — IAM role ARN to assume when calling Bedrock.
        - `region` string — AWS region used for STS when assuming the Bedrock inference role.
    - `credential_strategy` 'CREATOR' | 'EXECUTOR', nullable — Controls which principal's credentials are used when the platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on behalf of this run. - EXECUTOR (default when unset): credentials are sourced from the run's execution principal. For agent principals this produces a GitHub App installation token; for user principals this produces their personal OAuth token. - CREATOR: credentials are always sourced from the run creator, regardless of the execution principal. Useful when a service account executes the run but Git operations should authenticate as the human who triggered it. When unset, behavior is identical to EXECUTOR and no additional pre-flight validation is performed.
  - `agent_uid` string, uuid — UID of the agent that this schedule runs as
  - `metadata` RunMetadata — Custom key/value metadata attached to a run at creation time and immutable afterward. At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).
  - `environment` CloudEnvironmentConfig — Configuration for a cloud environment used by scheduled agents
    - `name` string — Human-readable name for the environment
    - `description` string, nullable — Optional description of the environment
    - `docker_image` string — Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")
    - `github_repos` GitHubRepo[] — List of GitHub repositories to clone into the environment
      - `owner` string, required — GitHub repository owner (user or organization)
      - `repo` string, required — GitHub repository name
    - `setup_commands` string[] — Shell commands to run during environment setup
    - `providers` ProvidersConfig — Optional cloud provider configurations for automatic auth
      - `gcp` GcpProviderConfig — GCP Workload Identity Federation settings
        - `project_number` string, required — GCP project number
        - `workload_identity_federation_pool_id` string, required — Workload Identity Federation pool ID
        - `workload_identity_federation_provider_id` string, required — Workload Identity Federation provider ID
        - `service_account_email` string — Optional GCP service account email to impersonate
      - `aws` AwsProviderConfig — AWS IAM role assumption settings
        - `role_arn` string, required — AWS IAM role ARN to assume
    - `failure_session_retention_minutes` integer, nullable — When set (1–60 minutes), a failed run using this environment keeps its session open for this many minutes so it can be inspected. null or absent means immediate teardown (disabled by default). The window is an idle window held open by the agent process itself: working in the session pushes the deadline out, so a session in active use is not torn down mid-debug. It ends early if the run's sandbox reaches its own deadline first. This policy applies to future failures of runs using this environment; it does not change the window a currently-failed run was already started with. Opting in keeps injected environment data (including secrets) alive and incurs compute usage for as long as the session is held open.
  - `created_at` string, date-time, required — Timestamp when the schedule was created (RFC3339)
  - `updated_at` string, date-time, required — Timestamp when the schedule was last updated (RFC3339)
  - `created_by` RunCreatorInfo
    - `type` 'user' | 'service_account' — Type of the creator principal
    - `uid` string — Unique identifier of the creator
    - `display_name` string — Display name of the creator
    - `email` string — Email address of the creator
    - `photo_url` string, uri — URL to the creator's photo
  - `updated_by` RunCreatorInfo
    - `type` 'user' | 'service_account' — Type of the creator principal
    - `uid` string — Unique identifier of the creator
    - `display_name` string — Display name of the creator
    - `email` string — Email address of the creator
    - `photo_url` string, uri — URL to the creator's photo
  - `history` ScheduledAgentHistoryItem — Scheduler-derived history metadata for a scheduled agent
    - `last_ran` string, date-time, nullable — Timestamp of the last successful run (RFC3339)
    - `next_run` string, date-time, nullable — Timestamp of the next scheduled run (RFC3339)
  - `scope` Scope — Ownership scope for a resource (team or personal)
    - `type` 'User' | 'Team', required — Type of ownership ("User" for personal, "Team" for team-owned)
    - `uid` string — UID of the owning user or team

## Other responses

- `401` — Authentication required
- `403` — No permission to pause schedule
- `404` — Schedule not found
- `500` — Internal server error

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)