---
title: "Set the session's goal, replacing any existing one [write]"
method: POST
path: "/sessions/{id}/goal"
---

# Set the session's goal, replacing any existing one \[write\]

`POST /sessions/{id}/goal`

## Request

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

Work starts immediately — no separate message is needed, and sending one is not how a goal begins. Criteria are optional: omitted, they are derived from the objective so completion is always judged against an explicit list, which the response returns and PATCH can correct. A criterion given as { text, command } is decided by running the command in the session's workspace (exit 0 = met) instead of by the grader. A person's message always outranks the loop: while a turn is running the goal waits, and takes the turn after it. Grading is a model call billed to the session; with an empty wallet deriving criteria is refused with 402 insufficient_credits. Setting a goal stops the run the goal it replaces had started.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- GoalInput
  - `objective` string, required: What the agent should work toward, in the user's words
  - `criteria` union[]: Independently checkable requirements; omitted = derived from the objective
    - 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: Self-started turns this goal may take before it stops. Omitted = 20; null = no iteration ceiling
  - `max_no_progress` integer, nullable: Consecutive turns without a tool call before stopping. Omitted = 3; null = no no-progress ceiling
  - `max_spend` object, nullable: Spend ceiling for this goal; null = none
    - `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: Wall-clock ceiling from the goal's start, extended by any time it spends paused

## Response `201`

Created

- 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 `201`
  - the `goal/consumed_spend` response's property type changed from `object` to no type for status `201`
  - removed the optional property `goal/consumed_spend/amount` from the response with the `201` status
  - removed the optional property `goal/consumed_spend/currency` from the response with the `201` status
  - …5 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/goal/post.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)