---
title: "Edit the goal in place [write]"
method: PATCH
path: "/sessions/{id}/goal"
---

# Edit the goal in place \[write\]

`PATCH /sessions/{id}/goal`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/goal`
- Auth: HTTP bearer

A course correction for an active or paused goal, not a restart: the iteration count and spend already consumed carry over. Editing criteria marks them as the caller's. A completed or stopped goal returns 409; POST a new goal to start another outcome.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- GoalPatch
  - `objective` string
  - `criteria` union[]
    - union
      - string
      - object
        - `text` string, required: What the criterion requires, in words
        - `command` string: Shell command run in the session's workspace; exit 0 means the criterion is met
  - `max_iterations` integer, nullable
  - `max_no_progress` integer, nullable
  - `max_spend` object, nullable
    - `amount` string, required: Whole US cents as an integer decimal string, e.g. "500" for $5.00
    - `currency` 'USD', required
  - `max_tokens` integer, nullable: Token ceiling for this goal: uncached input plus output, counted from the goal's start
  - `max_duration_minutes` integer, nullable

## Response `200`

OK

- object
  - `goal` Goal, required
    - `id` string, required: goal_…
    - `session` string, required: sess_…
    - `objective` string, required
    - `criteria` GoalCriterion[], required
      - `id` string, required: Stable within the goal, e.g. c1
      - `text` string, required
      - `command` string: Present when a shell command decides this criterion: it runs in the session's workspace after each iteration, and exit 0 means met. The grader cannot overturn it.
    - `criteria_source` 'user' | 'derived', required: Whether the caller supplied the criteria or the platform derived them from the objective
    - `status` 'active' | 'paused' | 'completed' | 'stopped', required
    - `stop_reason` 'failed' | 'max_iterations' | 'spend_budget' | 'token_budget' | 'time_budget' | 'no_progress' | 'cleared' | 'session_ended' | 'null', nullable, required: Why a stopped goal stopped; null in every other status
    - `iteration` integer, required: Self-started turns taken so far
    - `max_iterations` integer, required
    - `max_spend` MonetaryAmount, required: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `consumed_spend` MonetaryAmount, required: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `max_tokens` integer, nullable, required: Token ceiling for this goal; null = none
    - `consumed_tokens` integer, required: Uncached input plus output tokens over the session's metered model calls since the goal started, grading included. Calls on the session's own model subscription are not metered and not counted.
    - `deadline_at` string, date-time, nullable, required
    - `last_evaluation` GoalEvaluation, required: The grader's read of the most recent iteration.
      - `result` 'satisfied' | 'needs_revision' | 'failed', required
      - `explanation` string, required
      - `criteria` object[], required
        - `id` string, required
        - `met` boolean, required
        - `reason` string, required
        - `judged_by` 'grader' | 'command': What decided this criterion on this iteration
      - `iteration` integer, required
      - `at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 2 breaking, 2 warning, 5 info
  - added `#/components/schemas/MonetaryAmount` to the `goal/max_spend` response property `oneOf` list for the response status `200`
  - the `goal/consumed_spend` response's property type changed from `object` to no type for status `200`
  - removed the optional property `goal/consumed_spend/amount` from the response with the `200` status
  - removed the optional property `goal/consumed_spend/currency` from the response with the `200` status
  - …5 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/goal/patch.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)