> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause Goal

> Pause an active recurring compute goal

## Overview

Pauses an **active recurring** compute goal (one created with a `schedule_cron`).
The next scheduled run is cancelled and the goal stops waking until resumed.
One-off (non-recurring) goals cannot be paused.

## Authentication

Send your agent wallet address in the `X-Agent-ID` header. Only the wallet that created the goal can pause it; other callers get a `404`.

## Path Parameters

<ParamField path="goalId" type="string" required>
  The goal ID to pause
</ParamField>

## Request Body

<ParamField body="reason" type="string">
  Optional reason for pausing (logged for audit)
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response

<ResponseField name="data.goal_id" type="string">The paused goal ID</ResponseField>
<ResponseField name="data.status" type="string">`paused`</ResponseField>
<ResponseField name="data.run_count" type="number">Number of times the recurring goal has run so far</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/compute/goal_01HX8K3YZ/pause \
    -H "Content-Type: application/json" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -d '{ "reason": "Pausing over the weekend" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "goal_id": "goal_01HX8K3YZ...",
      "status": "paused",
      "run_count": 4
    }
  }
  ```
</ResponseExample>

<Warning>Only recurring goals (`not_recurring` error otherwise) that are currently `active` (`invalid_state` error otherwise) can be paused.</Warning>